Pass the TestKit coverage agent on the command line, move the shared TestKit directory - #207

Summary

Two problems with the TestKit directory, the Gradle user home of the builds that plugin-testlib runs through Gradle TestKit:

• Coverage tied it to one module. The TestKit coverage harness attached the JaCoCo agent by writing org.gradle.jvmargs into a gradle.properties in the TestKit directory, so it had to choose that directory itself, build/testkit-home per module. On CI it is empty on every run, so the first TestKit builds of each module redo the work a Gradle user home keeps, chiefly Gradle's instrumented copies of the JARs on the classpath of the plugin under test.
• The shared directory lived in each checkout. withSharedTestKitDirectory() put it under the repository root, in .gradle-test-kit. In core-jvm-compiler, that directory takes 1.76 GB in local tests, and every new worktree, of the same repository or another one, fills its own copy from scratch. That is costly when several agent sessions work in different worktrees or repositories on one machine.

This PR:

• Moves the agent to the command line. withTestKitCoverage() appends -Dorg.gradle.jvmargs=-javaagent:… to the runner arguments for builds started by executeTask, executeAndFail and runGradleBuild. The harness no longer chooses a TestKit directory, so coverage and the directory are independent of each other.
• Changes withSharedTestKitDirectory(). It takes an optional dir: File?. A given directory is used as is. Given none, the project uses caches/spine-testkit under the Gradle user home. The new GradleUserHome.kt looks the Gradle user home up in the order Gradle uses: the gradle.user.home system property, then the GRADLE_USER_HOME environment variable, then .gradle in the user's home directory. It composes the path with File, so Windows paths such as D:\a\.gradle work. @JvmOverloads keeps the method without arguments.
• Removes RootProject.testKitTempDir(), the old <repository root>/.gradle-test-kit. This is the breaking change.
• Makes the coverage property names public. TestKitCoverage.AGENT_PROPERTY and EXEC_DIR_PROPERTY hold them, so the spec and the KDoc refer to the constants instead of repeating the strings. config's buildSrc keeps its own copies, because it does not depend on this library.
• Collects TestKit coverage in plugin-testlib too. Its own tests now run with the agent like the other four TestKit modules. Today this adds no coverage, because the fixtures of GradleProjectSpec run only the java plugin, but it keeps every TestKit module on the same setup.
• Pulls config, with Say what a shared TestKit home saves config#833 and Set the TestKit directory apart from TestKit coverage config#834. useSharedTestKitDir() now sets Gradle's org.gradle.testkit.dir to caches/spine-testkit on every Test task, apart from enableTestKitCoverage(), so the other TestKit builds of all modules share the directory too. The pull also updates the versions pinned for Spine's own libraries.
• Adds tests: TestKitCoverageSpec for the appended argument and the no-op cases, GradleUserHomeSpec for the lookup, with two tests that run only on Windows, and new cases in GradleProjectSetupSpec for the choice of the directory.
• Updates the GradleProject KDoc: the consumer recipe for coverage, and a separate section on the TestKit directory.
• Bumps the version to 2.0.0-SNAPSHOT.460, as a breaking change, and updates the dependency reports.

An earlier revision added an io.spine.tools.gradle.testkit.coverage.home property for a shared directory, which SpineEventEngine/config#831 set. It duplicated Gradle's org.gradle.testkit.dir and was removed, here and in config#834.

Compatibility

• Breaking: RootProject.testKitTempDir() is removed.
• Callers of withSharedTestKitDirectory() still compile and link. They now share caches/spine-testkit under the Gradle user home instead of keeping .gradle-test-kit in each checkout. In the org, these are compiler (4 specs), core-jvm-compiler (4 integration tests) and ProtoTap (1 spec).
• A Gradle user home given only with -g: the test JVM does not see it, so the default falls back to GRADLE_USER_HOME or ~/.gradle. That only loses the sharing with that build's caches.
• Older plugin-testlib versions call withTestKitDir(<module>/build/testkit-home) themselves when coverage is on, which overrides org.gradle.testkit.dir, so they keep their per-module directories.
• Callers that use runner directly: compiler sets the environment and then calls executeTask, so it still gets the agent. ProtoTap and core-jvm-compiler call withJvmArguments(...), and explicit JVM arguments win over org.gradle.jvmargs from any source. Those tests got no worker coverage before this change either.
• Precedence: the appended argument replaces the test project's org.gradle.jvmargs, as the user-home gradle.properties did before.
• Build cache: with TestKit coverage on, plugin-testlib's test task is no longer cacheable, like those of the other four modules, so it reruns after clean.
• License headers: the touched files picked up the repo's current CodeMatters header, which the copyright tooling applies on edit.

Measurements

• Size: core-jvm-compiler's .gradle-test-kit takes 1.76 GB in local tests. In tool-base, the caches/ part of the shared directory takes about 250 MB, where per-module directories added up to 348 MB.

• Local wall-clock of the tests of the four coverage modules, measured with the earlier revision:

  TestKit directory	Time
  Per module, empty (every CI run before)	37 s
  Shared, empty (one-time)	53 s
  Shared, warm	14–16 s

• Windows PR run 41670107177, with the shared directory still empty: the build step took 733 s, against 837–901 s on the earlier runs that started with no cache, and no cache-lock timeouts.

• Coverage: the root Kover report with the TestKit exec files covers 3035 of 3157 lines and 989 of 1188 branches, against 2943 and 970 without them. Codecov reported 92.08% for 4c7ec60, against 92.03% on master, with misses unchanged at 122.

Test plan

• ./gradlew build dokkaGenerate, locally, after deleting the repository-root .gradle-test-kit and every per-module TestKit directory. None came back, and the TestKit builds wrote into ~/.gradle/caches/spine-testkit.
• GradleUserHomeSpec: 5 tests pass on macOS. The 2 Windows-only tests are skipped there.
• The Windows CI job runs the 2 Windows-only tests of GradleUserHomeSpec.
• GradleProjectSetupSpec, GradleProjectSpec, TestKitCoverageSpec and RootProjectSpec pass.
• Re-ran the TestKit modules' tests after deleting every build/jacoco-testkit: each of the four coverage modules wrote its testkit.exec (0.9–1.1 MB).
• With plugin-testlib's coverage on, no class in the root or the module Kover report changed.
• Pre-PR checks on an earlier revision: spine-code-review, kotlin-engineer, review-docs. The latest changes, the Gradle user home lookup and the new withSharedTestKitDirectory(), have not been re-reviewed.
• After this PR merges: a master run saves caches/spine-testkit, and later PR runs restore it.

🤖 Generated with Claude Code